Skip to content

feat: add uipath trace CLI command for trajectory visualization#1546

Open
DragosBobolea wants to merge 1 commit intomainfrom
feat/cli-trace-visualization
Open

feat: add uipath trace CLI command for trajectory visualization#1546
DragosBobolea wants to merge 1 commit intomainfrom
feat/cli-trace-visualization

Conversation

@DragosBobolea
Copy link
Copy Markdown
Member

@DragosBobolea DragosBobolea commented Apr 7, 2026

What

Adds a new uipath trace CLI command that visualizes agent execution traces as a Rich tree.

Problem

uipath run --trace-file and uipath eval --trace-file export raw OpenTelemetry spans to JSONL files, but there was no way to view them after the fact — you'd get a wall of JSON.

Solution

# Capture traces
uipath run main '{"query": "hello"}' --trace-file traces.jsonl

# Visualize
uipath trace traces.jsonl
Trace abcdef12…34567890
└── agent (12.5s) ✓
    ├── input: {"messages": [{"role": "user", "content": "Book a flight..."}]}
    ├── LLM (gpt-4o) (2.2s) ✓
    │   └── tokens: prompt=847, completion=156, total=1003
    ├── 🔧 search_flights (1.7s) ✓
    │   ├── input: {"origin": "SFO", "destination": "NRT"}
    │   └── output: {"flights": [...]}
    └── 🔧 book_flight (1.2s) ✓
        └── output: {"confirmation": {"booking_ref": "BK-UA837"}}
9 spans total

Features

Flag Purpose
(default) Span tree with input/output truncated to 200 chars
--full All attributes, no truncation
--no-input / --no-output Structure-only overview
--name "pattern" Filter spans by name (glob) — keeps ancestors
--contains "pattern" Keep full subtrees where any descendant matches
--span-type TOOL Filter by span_type attribute
--status error Filter by span status
--eval-id "name" Pick specific evaluation from verbose eval JSON

Supported inputs

  • JSONL from uipath run --trace-file / uipath eval --trace-file
  • JSON from uipath eval --verbose --output-file

Eval workflow

# Run eval set with tracing
uipath eval main eval-set.json --trace-file traces.jsonl

# Find the eval run where get_random_operator was called
uipath trace traces.jsonl --contains "get_random*"

Changes

  • New: packages/uipath/src/uipath/_cli/cli_trace.py — the command
  • New: packages/uipath/tests/cli/trace/ — 66 tests + fixtures
  • Modified: __init__.py — registered trace in lazy commands
  • Modified: CLI_REFERENCE.md, AGENTS.md, README.md, docs/cli/index.md — documentation

@DragosBobolea
feat: add uipath trace CLI command for trajectory visualization
206f34b 
Add a new `uipath trace` command that reads JSONL trace files (from
`uipath run --trace-file` or `uipath eval --trace-file`) and eval
verbose JSON output, rendering a Rich span tree showing the agent's
execution trajectory.

Features:
- Span tree with timing, status icons, and smart labels (LLM/tool/generic)
- Key attributes displayed by default (input, output, tokens, model name)
- `--full` mode shows all attributes with no truncation
- `--no-input`/`--no-output` for structural overview
- `--name` filter prunes the tree to matching spans + ancestors
- `--contains` extracts full subtrees where any descendant matches,
  useful for finding specific eval runs across a trace file
- `--span-type` and `--status` filters
- `--eval-id` to pick a specific evaluation from verbose JSON output
- Auto-detects JSONL vs eval JSON format

Includes 66 tests covering loading, tree building, filtering, rendering,
and CLI integration.
@DragosBobolea DragosBobolea force-pushed the feat/cli-trace-visualization branch from 4aed03b to 206f34b Compare April 7, 2026 14:58
@github-actions github-actions bot added test:uipath-langchain Triggers tests in the uipath-langchain-python repository test:uipath-llamaindex Triggers tests in the uipath-llamaindex-python repository labels Apr 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

test:uipath-langchain Triggers tests in the uipath-langchain-python repository test:uipath-llamaindex Triggers tests in the uipath-llamaindex-python repository

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@DragosBobolea